Anzeigen-Creatives mit der Select URL API rotieren

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Mit der Select URL API können Sie Shared Storage nutzen, um zu bestimmen, welches Creative ein Nutzer auf Websites sieht.

Werbetreibende oder Content-Produzenten können verschiedene Strategien zur Anzeigenrotation auf eine Kampagne anwenden und die Inhalte oder Creatives rotieren, um die Effektivität zu steigern. Mit der Select URL API können Sie verschiedene Rotationsstrategien wie die sequenzielle und die gleichmäßige Rotation auf verschiedenen Websites ausführen.

Mit der Creative-Rotation über die Select URL API können Sie Daten wie Creative-ID, Aufrufzahlen und Nutzerinteraktionen speichern, um zu bestimmen, welches Creative Nutzer auf verschiedenen Websites sehen.

Weitere Informationen zur zugrunde liegenden API und zur Funktionsweise der Auswahl finden Sie in der API-Dokumentation für die Select URL API.

Creative-Rotation ausprobieren

Wenn Sie die Creative-Rotation ausprobieren möchten, müssen die Select URL API und Shared Storage aktiviert sein:

• Wählen Sie unter chrome://settings/content/siteData die Option Allow sites to save data on your device oder Delete data sites have saved to your device when you close all windows aus.
• Wählen Sie unter chrome://settings/adPrivacy/sites die Option Site-suggested ads aus.

In unserer Live-Demo für freigegebenen Speicher finden Sie eine Liveversion der Codebeispiele in diesem Dokument.

Demo mit Codebeispielen

In diesem Fall gilt Folgendes:

• creative-rotation.js ist das Script eines Drittanbieters, das die zu rotierenden Inhalte sowie alle Daten definiert, anhand derer die nächsten Inhalte ausgewählt und angezeigt werden, z. B. Gewichte in diesem Beispiel. Dieses Script wird auf der Publisher-Seite ausgeführt. Dieses Script ruft das Shared Storage-Worklet auf, um anhand der verfügbaren Daten im Speicher und der Liste der URLs zu bestimmen, welche Inhalte angezeigt werden sollen.

• creative-rotation-worklet.js ist das Worklet für den freigegebenen Speicher des Drittanbieters, das die Rotationsstrategie abruft, berechnet, welche Inhalte als Nächstes veröffentlicht werden sollen, und diese Inhalte zurückgibt.

So funktioniert die Demo

1. Wenn ein Nutzer die Publisher-Seite besucht, wird das creative-rotation.js-Script des Drittanbieters auf der Seite geladen. Das Creative-Rotations-Script ist für das Laden und Ausführen des Worklets für den freigegebenen Speicher verantwortlich. Das Script stellt dem Worklet-Aufruf eine Liste von URLs zur Auswahl bereit.
2. Wenn der freigegebene Speicher im Worklet noch nicht initialisiert wurde, wird er mit der ursprünglichen Creative-Rotationsstrategie und dem Creative-Index initialisiert. Die in dieser Demo verwendete anfängliche Rotationsstrategie ist die sequenzielle Strategie.
3. Das Worklet liest den Rotationsmodus aus dem freigegebenen Speicher und gibt den Index der nächsten Anzeige zurück. Im sequenziellen Iterationsmodus wird auch der Creative-Index im freigegebenen Speicher mit dem neuen Wert aktualisiert, der für den nächsten Aufruf verwendet werden soll.Das Worklet gibt ein FencedFrameConfig- oder ein opaques URN-Objekt zurück, je nachdem, welcher resolveToConfig-Wert beim Aufrufen von selectURL verwendet wurde.
4. Das Script für die Creative-Rotation zeigt die ausgewählte Anzeige in einem Fenced Frame oder einem iFrame an. Weitere Informationen zu Rückgabetypen finden Sie im Dokument zum Rendern einer Anzeige.
5. Wenn ein Nutzer den Modus für die Anzeigenrotation ändert, aktualisiert das Shared Storage-Worklet den im Shared Storage gespeicherten Wert für den Modus für die Anzeigenrotation.
6. Wenn die Publisher-Seite aktualisiert wird, werden die Schritte 1 bis 4 wiederholt. So kann die nächste Anzeige basierend auf der ausgewählten Rotationsstrategie ausgewählt werden.

Codebeispiele

Im Folgenden finden Sie die Codebeispiele für creative-rotation.js und creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Schritt-für-Schritt-Anleitung mit Screenshots

1. Unter https://shared-storage-demo.web.app/ können Sie die Creative-Rotation mit der Select URL API und dem Shared Storage aufrufen. Wählen Sie die Demo „Creative-Rotation“ aus.

2. Sehen Sie sich die Demo als „Publisher A“ an. Sie werden zu https://shared-storage-demo-publisher-a.web.app/creative-rotation weitergeleitet. Auf der Seite werden nummerierte Inhalte basierend auf den in Shared Storage gespeicherten Creative-Rotationsdaten geladen, auf die über die Select URL API zugegriffen wird. Die Demomodi für die Creative-Rotation sind „Sequenziell“, „Gleichmäßige Verteilung“ und „Gewichtete Verteilung“. Das Worklet führt die Logik aus, um die Inhalte auszuwählen, die im IFrame angezeigt werden. Die folgende Abbildung zeigt die Seite des Publishers.

   
   

3. Wenn Sie sehen möchten, was im gemeinsamen Speicher gespeichert ist, rufen Sie in Chrome DevTools „Anwendung“ -> „Gemeinsamer Speicher“ auf. Für den freigegebenen Speicher werden zwei Einträge erstellt. Für die Quelle https://shared-storage-demo-publisher-a.web.app ist ein leerer Speicher verfügbar. Dieser enthält Speicherplatz, der für diesen Ursprung spezifisch ist, und bleibt für unsere Demo leer, da der Publisher nicht auf den freigegebenen Speicher schreiben muss. Hinweis: Für Publisher B wird ein ähnlicher Speicherplatz erstellt, wenn Sie diese Seite später für die Demo aufrufen.

   
   

4. Für den Ursprung https://shared-storage-demo-content-producer.web.app wird ein weiterer Shared Storage-Eintrag erstellt. Das ist der Speicherort des Drittanbieter-iFrames, der auf der Publisher-Seite eingebettet ist. Über diesen Speicher werden Daten zwischen den beiden verfügbaren Publishern ausgetauscht, um die Creative-Auswahl zu koordinieren. In diesem gemeinsamen Speicher werden Informationen zum angezeigten Creative und zur Rotationsstrategie gespeichert. Dazu werden zwei Schlüssel/Wert-Paare verwendet. Der erste Schlüssel in der Demo ist creative-rotation-index, dessen Wert der aktuelle Creative-Index im sequenziellen Modus ist. Der zweite Schlüssel ist creative-rotation-mode, der die verwendete Rotationsstrategie festlegt.

   
   

5. Wenn Sie die Seite im sequenziellen Modus aktualisieren, wird das nächste Creative in der Sequenz (1, 2, 3, 1, …) angezeigt. Der Wert für den Creative-Rotationsindex ändert sich im sequenziellen Modus entsprechend dem Index des angezeigten Creatives.

   
   

6. Wenn Sie den Modus für die Creative-Rotation über die Steuerschaltflächen ändern, wird der Wert für den Schlüssel „creative-rotation-mode“ in der entsprechenden Strategie aktualisiert. Anhand dieser Information wird im Worklet-Code das nächste Creative ausgewählt, das im iFrame angezeigt werden soll. Der für „creative-rotation-index“ gespeicherte Wert ändert sich bei anderen Iterationsmodi als „sequential“ nicht.

   
   

7. Rufen Sie die Seite für „Publisher B“ unter https://shared-storage-demo-publisher-b.web.app/creative-rotation auf. Im sequenziellen Modus sollte das angezeigte Creative das nächste Creative in der Sequenz sein, das beim Aufrufen der URL für „Publisher A“ angezeigt wird. Bei der Prüfung des freigegebenen Speichers für den Content-Produzenten stellen Sie fest, dass sowohl „Publisher A“ als auch „Publisher B“ denselben Speicher nutzen und dort die Einstellungen verwenden, um das nächste Creative auszuwählen und die zu verwendende Rotationsstrategie festzulegen.

   
   

8. Der freigegebene Speicher für „Publisher B“ ist leer, ähnlich wie der freigegebene Speicher von „Publisher A“.

   
   

   Anwendungsfälle

   In diesem Abschnitt finden Sie alle verfügbaren Anwendungsfälle für die Select URL API. Wir werden weitere Beispiele hinzufügen, sobald wir Feedback erhalten und neue Testfälle entdecken.

   • Anzeigen-Creatives rotieren: Speichern Sie Daten wie die Creative-ID und Nutzerinteraktionen, um zu ermitteln, welches Creative Nutzer auf verschiedenen Websites sehen.
   • Anzeigen-Creatives nach Häufigkeit auswählen: Anhand der Daten zur Wiedergabeanzahl können Sie ermitteln, welches Creative Nutzern auf verschiedenen Websites präsentiert wird.
   • A/B-Tests ausführen: Sie können einen Nutzer einer Testgruppe zuweisen und diese Gruppe dann in Shared Storage speichern, damit auf sie websiteübergreifend zugegriffen werden kann.
   • Angebote für bekannte Kunden anpassen: Sie können benutzerdefinierte Inhalte und Calls-to-Action basierend auf dem Registrierungsstatus oder anderen Nutzerstatus teilen.

Feedback geben und erhalten

Der Vorschlag für die Select URL API befindet sich in der aktiven Diskussion und Entwicklung und kann sich ändern.

Wir würden uns sehr über Ihr Feedback zur Select URL API freuen.

• Angebot: Sehen Sie sich das detaillierte Angebot an.
• Diskussion: Nehmen Sie an der laufenden Diskussion teil, um Fragen zu stellen und Ihre Erkenntnisse zu teilen.

Auf dem Laufenden bleiben

• Mailingliste: Melden Sie sich für unsere Mailingliste an, um aktuelle Informationen und Ankündigungen zu den APIs „Select URL“ und „Shared Storage“ zu erhalten.

Benötigst du Hilfe?

• Entwicklersupport: Im Repository für den Privacy Sandbox-Entwicklersupport können Sie sich mit anderen Entwicklern austauschen und Antworten auf Ihre Fragen erhalten.